Module pyglet.clock

Precise framerate calculation, scheduling and framerate limiting.

Measuring time

The tick and get_fps functions can be used in conjunction to fulfil most games' basic requirements:

from pyglet import clock
while True:
    dt = clock.tick()
    # ... update and render ...
    print 'FPS is %f' % clock.get_fps()

The dt value returned gives the number of seconds (as a float) since the last "tick".

The get_fps function averages the framerate over a sliding window of approximately 1 second. (You can calculate the instantaneous framerate by taking the reciprocal of dt).

Always remember to tick the clock!

Limiting frame-rate

The framerate can be limited:

clock.set_fps_limit(60)

This causes clock to sleep during each tick in an attempt to keep the number of ticks (frames) per second below 60.

The implementation uses platform-dependent high-resolution sleep functions to achieve better accuracy with busy-waiting than would be possible using just the time module.

Scheduling

You can schedule a function to be called every time the clock is ticked:

def callback(dt):
    print '%f seconds since last callback' % dt

clock.schedule(callback)

The schedule_interval method causes a function to be called every "n" seconds:

clock.schedule_interval(callback, .5)   # called twice a second

The schedule_once method causes a function to be called once "n" seconds in the future:

clock.schedule_once(callback, 5)        # called in 5 seconds

All of the schedule methods will pass on any additional args or keyword args you specify to the callback function:

def animate(dt, velocity, sprite):
   sprite.position += dt * velocity

clock.schedule(animate, velocity=5.0, sprite=alien)

You can cancel a function scheduled with any of these methods using unschedule:

clock.unschedule(animate)

Displaying FPS

The ClockDisplay class provides a simple FPS counter. You should create an instance of ClockDisplay once during the application's start up:

fps_display = clock.ClockDisplay()

Call draw on the ClockDisplay object for each frame:

fps_display.draw()

There are several options to change the font, color and text displayed within the __init__ method.

Using multiple clocks

The clock functions are all relayed to an instance of Clock which is initialised with the module. You can get this instance to use directly:

clk = clock.get_default()

You can also replace the default clock with your own:

myclk = clock.Clock() clock.set_default(myclk)

Each clock maintains its own set of scheduled functions and FPS limiting/measurement. Each clock must be "ticked" separately.

Multiple and derived clocks potentially allow you to separate "game-time" and "wall-time", or to synchronise your clock to an audio or video stream instead of the system clock.

Classes

	Clock Class for calculating and limiting framerate, and for calling scheduled functions.
	ClockDisplay Display current clock values, such as FPS.

Functions

	set_default(default) Set the default clock to use for all module-level functions.
Clock	get_default() Return the Clock instance that is used by all module-level clock functions.
float	tick(poll=False) Signify that one frame has passed on the default clock.
float	get_sleep_time(sleep_idle) Get the time until the next item is scheduled on the default clock.
float	get_fps() Return the current measured FPS of the default clock.
	set_fps_limit(fps_limit) Set the framerate limit for the default clock.
	get_fps_limit() Get the framerate limit for the default clock.
	schedule(func, args, *kwargs) Schedule 'func' to be called every frame on the default clock.
	schedule_interval(func, interval, args, *kwargs) Schedule 'func' to be called every 'interval' seconds on the default clock.
	schedule_interval_soft(func, interval, args, *kwargs) Schedule 'func' to be called every 'interval' seconds on the default clock, beginning at a time that does not coincide with other scheduled events.
	schedule_once(func, delay, args, *kwargs) Schedule 'func' to be called once after 'delay' seconds (can be a float) on the default clock.
	unschedule(func) Remove 'func' from the default clock's schedule.
	test_clock()

Variables

__package__ = 'pyglet'

Function Details

set_default

set_default(default)

Set the default clock to use for all module-level functions.

By default an instance of Clock is used.

Parameters:

default : Clock: The default clock to use.

get_default

get_default()

Return the Clock instance that is used by all module-level clock functions.

Returns:: Clock: The default clock.

tick

tick(poll=False)

Signify that one frame has passed on the default clock.

This will call any scheduled functions that have elapsed.

Parameters:

poll : bool

If True, the function will call any scheduled functions but will not sleep or busy-wait for any reason. Recommended for advanced applications managing their own sleep timers only.

Since pyglet 1.1.

Returns:

float: The number of seconds since the last "tick", or 0 if this was the first frame.

get_sleep_time

get_sleep_time(sleep_idle)

Get the time until the next item is scheduled on the default clock.

See Clock.get_sleep_time for details.

Parameters:

sleep_idle : bool: If True, the application intends to sleep through its idle time; otherwise it will continue ticking at the maximum frame rate allowed.

Returns:

float: Time until the next scheduled event in seconds, or None if there is no event scheduled.

Since: pyglet 1.1

set_fps_limit

set_fps_limit(fps_limit)

Set the framerate limit for the default clock.

Parameters:

fps_limit : float: Maximum frames per second allowed, or None to disable limiting.

Deprecated: Use pyglet.app.run and schedule_interval instead.

get_fps_limit

get_fps_limit()

Get the framerate limit for the default clock.

Returns:: The framerate limit previously set by set_fps_limit, or None if no limit was set.

schedule

schedule(func, *args, **kwargs)

Schedule 'func' to be called every frame on the default clock.

The arguments passed to func are dt, followed by any *args and **kwargs given here.

Parameters:

func : function: The function to call each frame.

schedule_interval

schedule_interval(func, interval, *args, **kwargs)

Schedule 'func' to be called every 'interval' seconds on the default clock.

The arguments passed to 'func' are 'dt' (time since last function call), followed by any *args and **kwargs given here.

Parameters:

func : function: The function to call when the timer lapses.
interval : float: The number of seconds to wait between each call.

schedule_interval_soft

schedule_interval_soft(func, interval, *args, **kwargs)

Schedule 'func' to be called every 'interval' seconds on the default clock, beginning at a time that does not coincide with other scheduled events.

The arguments passed to 'func' are 'dt' (time since last function call), followed by any *args and **kwargs given here.

Parameters:

func : function: The function to call when the timer lapses.
interval : float: The number of seconds to wait between each call.

See Also: Clock.schedule_interval_soft

Since: pyglet 1.1

schedule_once

schedule_once(func, delay, *args, **kwargs)

Schedule 'func' to be called once after 'delay' seconds (can be a float) on the default clock. The arguments passed to 'func' are 'dt' (time since last function call), followed by any *args and **kwargs given here.

If no default clock is set, the func is queued and will be scheduled on the default clock as soon as it is created.

Parameters:

func : function: The function to call when the timer lapses.
delay : float: The number of seconds to wait before the timer lapses.

unschedule

unschedule(func)

Remove 'func' from the default clock's schedule. No error is raised if the func was never scheduled.

Parameters:

func : function: The function to remove from the schedule.